External Windows 1
Volume Number: 7
Issue Number: 2
Column Tag: XCMD Corner
By Donald Koscheka, Contributing Editor
Note: Source code files accompanying article are located on MacTech CD-ROM orsource code disks.
This month, we are going to take a comprehensive look at external window
management in Hypercard 2.0. External windows are easy to work with and if you’ve
been programming the Macintosh for any amount of time, you won’t have any trouble
with them. If you’re a newcomer to the field, external windows are an excellent place to
start as the core of an external window management system is the same as any
Macintosh application -- the event loop.
Hypercard 2.0 supports external windows in a much more generous fashion than
was available under Hypercard 1.x. For one thing, external windows can support
callbacks so that you can interface the window directly to Hypercard which was not
possible under Hypercard 1.x. External windows do not pre-empt the card, both
Hypercard windows and external windows (let’s call them xwindoids) coexist quite
nicely in HC2.0.
Windows in Hypercard 2.0 exist in one of two layers, the document layer and the
floating layer. Palettes live in the floating layer. Windows in this layer never get
activate events -- they are active at all times that they are visible. The toolbox call to
Front window() will always return a pointer to a floating window if any floating
windows are visible. The frontmost document window will be reported throughout the
Hypercard callback, FrontDocWindow().
The document layer is the standard Macintosh windowing environment.
Documents behave like typical Macintosh windows, they respond to all standard
Macintosh events as well as some Hypercard specific events.
Opening Windows
Listing 1, xwindoids.c, depicts an xcmd that creates a window in the document
layer. The window is created by a call to the Hypercard callback, NewXWindow(). In
order for Hypercard to add your window to its document or floating layer, you must
open your window using this callback or its close cousin, GetNewXWindow() which
opens a window from a resource template. You can still use NewWindow if you have
some old xcmd that supports external windows, but windows created by directly calling
the window manager will not get Hypercard events nor will they be able to make
callbacks to Hypercard.
The prototype for these two new callbacks are:
/* 1 */
extern pascal WindowPtr NEWXWINDOW(XCmdPtr paramPtr, Rect
*boundsRect, StringPtr title, Boolean visible, short procID, Boolean
color, Boolean floating);
extern pascal WindowPtr GETNEWXWINDOW(XCmdPtr paramPtr, ResType
templateType, short templateID, Boolean color, Boolean floating);
Both callbacks return a standard window manager WindowPtr so there is nothing
new there. Being callbacks, both routines need to have the paramPtr passed in. Notice
that Apple changed the name of the paramPtr struct form XCmdBlkPtr to XCmdPtr. The
structure remains unchanged however.
For NewXWindow, the rectangle, title, visible and procID all correspond to the
equivalent parameters in NewWindow(). Similarly, GetNewXWindow() gets passed the
id of the resource window template. You have the option of opening color windows and
of making them floating or document windows by assigning true or false for these
parameters. Listing 1 opens a non-color document window.
XWindoids Events
The xcmd creates the window and does nothing more with the window for the time
being. It returns to Hypercard which will subsequently call this very same xcmd with
an xOpenEvt hypercard event. This is important because it represents a departure
away from the way we are used to thinking about xcmds. When an xcmd creates a
window, it is said to “own” that window. Any events that must be handled for that
window will be sent to that xcmd. Thus, Hypercard will call upon the xcmd to handle
events in a manner that is transparent to the rest of Hypercard.
We detect whether the xcmd is being sent an event by checking the paramCount
field in the xcmd command block. By convention, if the number of parameters is less
than 0, then we have an event. In this case, Hypercard passes us a pointer to a
Hypercard event record in params[0] . The hypercard event record looks like this:
/* 2 */
typedef struct XWEventInfo *XWEventInfoPtr;
struct XWEventInfo {
EventRecord event;
WindowPtr eventWindow;
long eventParams[9];
Handle eventResult;
};
The first field in the record is the standard Macintosh event manager event
record. Its fields correspond to the normal usage of an event record. The next field is a
pointer to the window that the event is meant for. This is provided for the case of xcmds
that handle more than 1 window. Our xcmd handles only one window so we can use this
field to point to that window rather than calling FrontWindow() which might return
the wrong result (since it always passes a visible palette as the front window).
EventParams and eventResult are used to pass information about specific events
to the xcmd. None of the events in xwindoids.c uses these fields so we’ll reserve their
discussion for the future.
If paramCount is zero, we dispatch the parameter block to our event handler, in
this case a routine called “HandleHCEvent”. HandleHCEvent must first dereference the
hypercard event record so that all of its fields are accessible. Next, we set passFlag to
true. I’m still trying to piece together the rules for this. It seems that you pass true
back to hypercard to tell it to handle the event and false to tell it not to handle the event.
If anyone can illuminate this better than that, I will be happy to publish your
explanation as the use of this field in relation to events is only briefly discussed in the
Hypercard 2.0 xcmd technical documentation. In the meantime, I’ve been using trial
and error to get the value of passflag right for each event.
Once the event record is dereferenced, HandleHCEvent closely resembles the
event processing switch of any generic Macintosh Application. This is good, you can
port your code to Hypercard very quickly by using listing 1 as a template. There is no
need to call getNextEvent or WaitNextEvent. Hypercard is taking each event and
deciding in turn whether it needs to be dispatched to an external window. Keep in mind
that in order for an xcmd to get events, it must have a window associated with it. This
is not quite according to Hoyle but it will do. Rather than address each case in the
switch, let’s follow the event processing in the order that the events will be called.
Upon opening a new window, the very first event to be called will be xOpenEvt.
It is here that we allocate any private storage needed by the window. In the case of
xwindoids.c, we will fill the window up with a text edit record just to show that we can
do some editing in the window. We store the TextEdit record off the window’s refcon so
that we can find it easily. Use any storage schema that you’re comfortable with. If
you’re using Think C, A4 Globals will work okay here also, make sure that you set up
A4 first. A quick sideline: Think compilers do an outstanding job of supporting the
kinds of features that you’ll need to write non-A5 relative code. I use Think “C” or
Think Pascal exclusively for writing xcmds because of the multi-segment support and
the ability to set up my own environment based off register A4.
Note that I only show the window, which was created as invisible only after
taking the xOpenEvt. I figure that it’s better not to show the window until Hypercard is
ready to deal with it which is at xOpenEvt time. That way the window does stare back at
me with that slack-jawed blank content region look while I’m waiting for Hypercard to
tell me that it’s okay to start using it. We need to set passFlag to true on xOpenEvt to
tell hypercard that we took the event. From here on out, we will get all events intended
for this window.
The next event we get is the activateEvt. This is the standard event manager
activate event and is only passed to Document windows. Floating windows are always
active so they don’t get activate events. We first check to see if we’re going active or
inactive. If the former, then we can activate our text edit record and advise Hypercard
that our window now has the edit (or input) focus by calling BeginXWEdit. Once this
callback is made, Hypercard will send all keydowns to us until one of two events occurs:
our window becomes inactive or Hypercard tells us to give up edit by sending us the
xGiveUpEditEvt event. In order to be Hypercard friendly, we need to be prepared to
give up the edit focus at any time, Hypercard will tell us when, but we should be
courteous and acknowledge the event if we have the edit focus.
Once we become the active window, we will get the update evt followed by any
number of events until such time as our window is closed. If the user clicks on the
goaway box, Hypercard will advise us that our window is closing. First, the window
will go inactive. Next we will get the XWCloseEvt event. At this time, we should close
down our internal data structures associated with the window (such as the TEHandle).
In listing 1, I hide the window here also. There is no need to call closeWindow or
otherwise deallocate the window structures, Hypercard will do that for you.
As you can see from listing 1, there are a lot of new Hypercard events to talk
about and we will get to the rest of them in future columns. The rest of event handling
is standard Macintosh stuff and seems to work just fine. Note that in the null event
handler (default:) we need to adjust the cursor ourselves if the mouse is in the edit box.
I found that unless you set passflag to false, Hypercard will set the cursor back to the
arrow on you here resulting in a flickering cursor.
Handling mousedown events is little different than you might be accustomed to
also. In the case of the goaway control, we do the usual tracking but instead of closing
the window directly, we issue a callback, CLOSEXWINDOW, to hypercard in effect
asking hypercard to close the window for us. Hypercard will respond that the window
is ready to be closed by sending us back an XWCloseEvt at some time in the future.
Between the CloseXWindow call and the XWCloseEvt event, the window is in limbo, it
might make sense to hide the window here to give the user the sense that the window
closed but I find that the latency between these events just isn’t long enough to worry
about that.
Dragging the window seems to be handled directly by Hypercard so we don’t do
anything with that event. I handle the incontent hits as if this were a normal
application. It seems to work fine although you do need to set the passFlag to false after
handling the mousedown or Hypercard will get confused.
Similarly, key events can be handled directly. Command keys are handled directly
by Hypercard so there is no need to test to see if we have a menu key. Again, we set
passflag to false to tell hypercard that we took this event. If we set passflag to true
here, hypercard will try to handle the event going so far as to call us back with an
XWGiveUpEdit event. That would be bad.
Listing 1 is by no means complete. It doesn’t handle scrolling or the grow box
yet. You may want to begin your own investigations by adding these features to listing
1. In any event, happy hacking. If you discover anything that you would like to share
with the rest of the Mac community, please drop me a line on AppleLink (D6845) or
America On Line (AFC Donald).
Listing 1:
/********************************/
/* File: xwindoid.c */
/* */
/* A sample XCMD for Hypercard */
/* 2.0 that displays and handles*/
/* an external window. */
/* */
/* Well-behaved XCMDs for HC2.0 */
/* will respond to the ! and ? */
/* requests by returning version*/
/* and usage information */
/* respectively. */
/* */
/* ---------------------------- */
/* ©1990, Donald Koscheka */
/* All Rights Reserved */
/********************************/
/*
Project:
ANSI-A4 -- standard "C" libraries assembled
off of register A4
MacTraps
HyperXLib-- Hypercard 2.0 callback library available from
Apple Computer, Inc.
xwindoid.c (contents of listing 1)
Set Project Type:
Type == XCMD | XFCN
Name == xwindoid
id == -32768..32767
xwindoid "?
xwindoid "!
put the result
OR
Put xwindoid( "?" )
Put xwindoid( "!" )
*/
#include
#include
#include
#ifndef NIL
#define NIL (void *)0L
#endif
#define ETX 0x03
#define BS 0x08
#define TAB 0x09
#define LF 0x0A
#define NEWLINE 0x0D
#define CR 0x0D
#define LEFT_ARROW 0x1C
#define RIGHT_ARROW 0x1D
#define UP_ARROW 0x1E
#define DOWN_ARROW 0x1F
/* Multifinder events and masks */
#ifndef MouseMovedEvt
#define MouseMovedEvt 0xFA
#endif
#ifndef SuspendResumeEvt
#define SuspendResumeEvt 0x01
#endif
#ifndef ResumeEvtMask
#define ResumeEvtMask 0x01
#endif
#ifndef ConvertScrapMask
#define ConvertScrapMask 0x02
#endif
pascal void HandleHCEvent( XCmdPtr pp );
Handle strToParam( str )
char *str;
/***************************
* Given a pointer to a string,
* copy that string into a handle
* and return the handle.
*
* The input and output strings
* are both null-terminated
***************************/
{
Handle outH = NIL;
long len = 0;
len = strlen( str );
if( len )
if( outH = NewHandle( len ) )
BlockMove( str, *outH, len + 1 );
return( outH );
}
pascal void main( pp )
XCmdPtr pp;
{
Handle answer = NIL;
char *str;
long len;
WindowPtr wind;
TEHandle hTE;
Rect bounds;
pp->returnValue = NIL;
if( pp->paramCount < 0 ){
HandleHCEvent( pp );
return;
}
if (pp->paramCount == 1){
if ( **(pp->params[0]) == '!' ){
pp->returnValue = strToParam("\pxwindoid XCMD, version 1.0,
©1990, Donald Koscheka");
return;
}
if ( **(pp->params[0]) == '?' ){
pp->returnValue = strToParam("\pSimple xwindoid handler.");
return;
}
}
/* now open a window to play with */
bounds.top = bounds.left = 0;
bounds.bottom = 320;
bounds.right = 500;
wind = NEWXWINDOW( pp, &bounds, "\pSample Window", FALSE,
documentProc, FALSE, FALSE);
CenterWindow( wind );
}
pascal void HandleHCEvent( XCmdPtr pp )
/**********************************
* Handle events in our xWindows
* returns true if the event was handled ok
**********************************/
{
XWEventInfoPtr ip = pp->params[0];
WindowPtr whichWindow;
short windoPart;
TEHandle hTE;
Rect bounds;
Point hit;
char theKey;
GrafPtr oldPort;
short extend;
pp->passFlag = TRUE; /* seems to be more often the case */
switch( ip-> event.what ){
case mouseDown:
windoPart = FindWindow( ip-> event.where, & whichWindow );
if( whichWindow )
switch ( windoPart ){
case inGoAway:
if (TrackGoAway( whichWindow, ip-> event.where) ){
CLOSEXWINDOW( pp, whichWindow );
pp->passFlag = FALSE;
}
break;
case inDrag:
/* handled by hypercard */
break;
case inGrow:
break;
case inContent:
if ( whichWindow == FrontWindow() ){
GetPort( &oldPort );
SetPort( ip-> eventWindow );
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
hit = ip-> event.where;
GlobalToLocal( &hit );
bounds = (*hTE)->viewRect;
if( PtInRect( hit, &bounds ) ){
extend = (short)ip-> event.modifiers && shiftKey;
TEClick( hit, extend, hTE);
}
SetPort( oldPort );
}else
SelectWindow( whichWindow );
pp->passFlag = FALSE;
break;
default:
break;
}/* window part */
break;
case mouseUp:
break;
case keyDown:
case autoKey:
/* the command key will be handled by hypercard */
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
GetPort( &oldPort );
SetPort( ip-> eventWindow );
theKey = ip-> event.message & 0xFF;
switch( theKey ){
case TAB:
break;
case ETX:
break;
case LEFT_ARROW:
case RIGHT_ARROW:
case UP_ARROW:
case DOWN_ARROW:
break;
case BS:
default:
TEKey( theKey, hTE );
break;
}/* switch( theKey ) */
SetPort( oldPort );
pp->passFlag = FALSE;
break;
case activateEvt:
if ( ip-> event.modifiers & activeFlag ){
BEGINXWEDIT( pp, ip-> eventWindow );
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
TEActivate( hTE );
}
else{
ENDXWEDIT( pp, ip-> eventWindow );
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
TEDeactivate( hTE );
}
break;
case updateEvt:
BeginUpdate( ip-> eventWindow );
DrawGrowIcon( ip-> eventWindow );
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
bounds = (*hTE)->viewRect;
TEUpdate( &bounds, hTE );
EndUpdate( ip-> eventWindow );
break;
case app4Evt:
{
unsigned char *evtType = &(ip-> event.message);
switch( *evtType ){
case MouseMovedEvt:
break;
case SuspendResumeEvt:
break;
}
}
break;
/****************************************/
/* THE HYPERCARD EVENTS */
/****************************************/
case xOpenEvt:
/* for illustrative purposes, we */
/* add a text edit field to the */
/* window */
SetPort( ip-> eventWindow );
bounds = ip-> eventWindow->portRect;
bounds.top += 4;
bounds.left +=4;
bounds.bottom -= 16;
bounds.right -= 16;
hTE = TENew( &bounds, &bounds );
(*hTE)->txFont = courier;
(*hTE)->txFace = 0;
(*hTE)->txSize = 10;
SetWRefCon( ip-> eventWindow, (long)hTE );
ShowWindow( ip-> eventWindow );
break;
case xCloseEvt:
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
TEDispose( hTE );
HideWindow( ip-> eventWindow );
break;
case xGiveUpEditEvt:
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
TEDeactivate( hTE );
break;
case xEditUndo:
break;
case xEditCut:
break;
case xEditCopy:
break;
case xEditPaste:
break;
case xEditClear:
break;
default:
GetPort( &oldPort );
SetPort( ip-> eventWindow );
GetMouse( &hit );
hTE = (TEHandle)GetWRefCon( ip-> eventWindow );
bounds = (*hTE)->viewRect;
if( PtInRect( hit, &bounds ) ){
SetCursor( *GetCursor(iBeamCursor) );
}
else
InitCursor();
TEIdle( hTE );
pp->passFlag = FALSE;
SetPort( oldPort );
}/* switch theEvent->what */
}